3D Graphics Programming with QuickDraw 3D 1.5.4

Creating and Accessing Windows Storage Objects

QuickDraw 3D provides routines for creating and managing Windows storage objects.

Q3Win32Storage_New

You use the Q3Win32Storage_New function to create a Windows storage object.



 
TQ3StorageObject Q3Win32Storage_New (const HANDLE hFile);

hFile: A handle to a file.

DESCRIPTION

The Q3Win32Storage_New function returns, as its function result, a new storage object associated with the file specified by the hFile parameter. The specified file is assumed to be closed. QuickDraw 3D opens the file and, when the associated storage object is closed or disposed of, QuickDraw 3D closes the file. If Q3Win32Storage_New cannot create a new storage object, it returns the value NULL .

EXAMPLES

The HANDLE type is a native Windows entity that's created using the Windows CreateFile call. The following illustrates a typical way of using this call to read an existing variable of type HANDLE :



 
        hFile = CreateFile(

            pathName,               // pointer to name of the file 

            GENERIC_READ,           // access (read-write) mode 

            0,                      // share mode 

            NULL,                   // pointer to security descriptor 

            OPEN_EXISTING,          // how to create 

            FILE_ATTRIBUTE_NORMAL,  // file attributes 

            NULL                    // handle to file with attributes

                                    // to copy  

        );

        A3Assert(hFile != INVALID_HANDLE_VALUE);

        A3Assert((srcStorage = Q3Win32Storage_New(hFile)) != NULL);

The following is a typical way of using the Windows CreateFile call to write to a variable of type HANDLE :



 
        hFile = CreateFile(

            pathName,                   // pointer to name of the file 

            GENERIC_WRITE,              // access (read-write) mode 

            0,                          // share mode 

            NULL,                       // pointer to security descriptor 

            CREATE_NEW,                 // how to create 

            FILE_ATTRIBUTE_NORMAL,      // file attributes 

            NULL                        // handle to file with

                                        // attributes to copy  

        );



 
        A3Assert(hFile != INVALID_HANDLE_VALUE);

        A3Assert((dstStorage = Q3Win32Storage_New(hFile)) != NULL);

Q3Win32Storage_Get

You can use the Q3Win32Storage_Get function to get the file associated with a Windows storage object.



 
TQ3Status Q3Win32Storage_Get (

                     TQ3StorageObject storage,

                     const HANDLE *hFile);

storage: A Windows storage object.
hFile: On exit, a handle to the file associated with the specified storage object.

DESCRIPTION

The Q3Win32Storage_Get function returns, through the hFile parameter, a handle to the file associated with the Windows storage object specified by the storage parameter.

Q3Win32Storage_Set

You can use the Q3Win32Storage_Set function to set the file associated with a Windows storage object.



 
TQ3Status Q3Win32Storage_Set (

                     TQ3StorageObject storage,

                     const HANDLE hFile);

storage: A Windows storage object.
hFile: A handle to a file.

DESCRIPTION

The Q3Win32Storage_Set function sets the file associated with the Windows storage object specified by the storage parameter to the file specified by the hFile parameter.